<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  
  <title>API 接口规范 | 上海科鹄网络科技有限公司</title>
  <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
  <meta name="description" content="整体规范建议采用RESTful 方式来实施。">
<meta name="keywords" content="RESTful">
<meta property="og:type" content="article">
<meta property="og:title" content="API 接口规范">
<meta property="og:url" content="http://ikohoo.com/blog/2017/09/07/api-specification/index.html">
<meta property="og:site_name" content="上海科鹄网络科技有限公司">
<meta property="og:description" content="整体规范建议采用RESTful 方式来实施。">
<meta property="og:updated_time" content="2017-09-07T08:40:40.535Z">
<meta name="twitter:card" content="summary">
<meta name="twitter:title" content="API 接口规范">
<meta name="twitter:description" content="整体规范建议采用RESTful 方式来实施。">
  
    <link rel="alternate" href="/atom.xml" title="上海科鹄网络科技有限公司" type="application/atom+xml">
  
  
    <link rel="icon" href="/favicon.png">
  
  
    <link href="//fonts.googleapis.com/css?family=Source+Code+Pro" rel="stylesheet" type="text/css">
  
  <link rel="stylesheet" href="/blog/css/style.css">
  

</head>

<body>
  <div id="container">
    <div id="wrap">
      <header id="header">
  <div id="banner"></div>
  <div id="header-outer" class="outer">
    <div id="header-title" class="inner">
      <h1 id="logo-wrap">
        <a href="/blog/" id="logo">上海科鹄网络科技有限公司</a>
      </h1>
      
        <h2 id="subtitle-wrap">
          <a href="/blog/" id="subtitle">国内领先的云计算和大数据解决方案咨询服务商</a>
        </h2>
      
    </div>
    <div id="header-inner" class="inner">
      <nav id="main-nav">
        <a id="main-nav-toggle" class="nav-icon"></a>
        
          <a class="main-nav-link" href="/blog/">Home</a>
        
          <a class="main-nav-link" href="/blog/archives">Archives</a>
        
      </nav>
      <nav id="sub-nav">
        
          <a id="nav-rss-link" class="nav-icon" href="/atom.xml" title="Flux RSS"></a>
        
        <a id="nav-search-btn" class="nav-icon" title="Rechercher"></a>
      </nav>
      <div id="search-form-wrap">
        <form action="//google.com/search" method="get" accept-charset="UTF-8" class="search-form"><input type="search" name="q" class="search-form-input" placeholder="Search"><button type="submit" class="search-form-submit">&#xF002;</button><input type="hidden" name="sitesearch" value="http://ikohoo.com/blog"></form>
      </div>
    </div>
  </div>
</header>
      <div class="outer">
        <section id="main"><article id="post-api-specification" class="article article-type-post" itemscope itemprop="blogPost">
  <div class="article-meta">
    <a href="/blog/2017/09/07/api-specification/" class="article-date">
  <time datetime="2017-09-07T07:23:22.000Z" itemprop="datePublished">2017-09-07</time>
</a>
    
  <div class="article-category">
    <a class="article-category-link" href="/blog/categories/RESTful-API/">RESTful API</a>
  </div>

  </div>
  <div class="article-inner">
    
    
      <header class="article-header">
        
  
    <h1 class="article-title" itemprop="name">
      API 接口规范
    </h1>
  

      </header>
    
    <div class="article-entry" itemprop="articleBody">
      
        <p>整体规范建议采用RESTful 方式来实施。</p>
<a id="more"></a>
<h1 id="1-协议"><a href="#1-协议" class="headerlink" title="1. 协议"></a>1. 协议</h1><p>API与用户的通信协议，总是使用HTTPs协议，确保交互数据的传输安全。</p>
<h1 id="2-域名"><a href="#2-域名" class="headerlink" title="2. 域名"></a>2. 域名</h1><p>应该尽量将API部署在专用域名之下。<br><a href="https://api.example.com" target="_blank" rel="external">https://api.example.com</a><br>如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。<br><a href="https://example.org/api/" target="_blank" rel="external">https://example.org/api/</a></p>
<h1 id="3-api版本控制"><a href="#3-api版本控制" class="headerlink" title="3. api版本控制"></a>3. api版本控制</h1><p>应该将API的版本号放入URL。<br><a href="https://api.example.com/v{n}/" target="_blank" rel="external">https://api.example.com/v{n}/</a><br>另一种做法是，将版本号放在HTTP头信息中，但不如放入URL方便和直观。Github采用这种做法。<br>采用多版本并存，增量发布的方式<br>v{n} n代表版本号,分为整形和浮点型<br>整形的版本号: 大功能版本发布形式；具有当前版本状态下的所有API接口 ,例如：v1,v2<br>浮点型：为小版本号，只具备补充api的功能，其他api都默认调用对应大版本号的api 例如：v1.1 v2.2</p>
<h1 id="4-API-路径规则"><a href="#4-API-路径规则" class="headerlink" title="4. API 路径规则"></a>4. API 路径规则</h1><p>路径又称”终点”（endpoint），表示API的具体网址。<br>在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的”集合”（collection），所以API中的名词也应该使用复数。<br>举例来说，有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。<br><a href="https://api.example.com/v1/products" target="_blank" rel="external">https://api.example.com/v1/products</a></p>
<p><a href="https://api.example.com/v1/users" target="_blank" rel="external">https://api.example.com/v1/users</a></p>
<p><a href="https://api.example.com/v1/employees" target="_blank" rel="external">https://api.example.com/v1/employees</a></p>
<h1 id="5-HTTP请求方式"><a href="#5-HTTP请求方式" class="headerlink" title="5. HTTP请求方式"></a>5. HTTP请求方式</h1><p>对于资源的具体操作类型，由HTTP动词表示。<br>常用的HTTP动词有下面四个（括号里是对应的SQL命令）。<br>GET（SELECT）：从服务器取出资源（一项或多项）。<br>POST（CREATE）：在服务器新建一个资源。<br>PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。<br>DELETE（DELETE）：从服务器删除资源。<br>下面是一些例子。<br>GET /product：列出所有商品<br>POST /product：新建一个商品<br>GET /product/ID：获取某个指定商品的信息<br>PUT /product/ID：更新某个指定商品的信息<br>DELETE /product/ID：删除某个商品<br>GET /product/ID/purchase ：列出某个指定商品的所有投资者<br>get /product/ID/purchase/ID：获取某个指定商品的指定投资者信息</p>
<h1 id="6-过滤信息"><a href="#6-过滤信息" class="headerlink" title="6. 过滤信息"></a>6. 过滤信息</h1><p>如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。<br>下面是一些常见的参数。<br>?limit=10：指定返回记录的数量<br>?offset=10：指定返回记录的开始位置。<br>?page=2&amp;per_page=100：指定第几页，以及每页的记录数。<br>?sortby=name&amp;order=asc：指定返回结果按照哪个属性排序，以及排序顺序。<br>?producy_type=1：指定筛选条件</p>
<h1 id="7-API-传入参数"><a href="#7-API-传入参数" class="headerlink" title="7. API 传入参数"></a>7. API 传入参数</h1><p>传入参数分为4种类型：<br>地址栏参数</p>
<ul>
<li>restful 地址栏参数 /api/v1/product/122 122为产品编号，获取产品为122的信息</li>
<li>get方式的查询字串 见过滤信息小节<br>请求body数据<br>cookie<br>request header<br>cookie和header 一般都是用于OAuth认证的2种途径</li>
</ul>
<h1 id="8-返回数据"><a href="#8-返回数据" class="headerlink" title="8. 返回数据"></a>8. 返回数据</h1><p>只要api接口成功接到请求，就不能返回200以外的HTTP状态。<br>为了保障前后端的数据交互的顺畅，建议规范数据的返回，并采用固定的数据格式封装。<br>接口返回模板：</p>
<p>  {<br>      status:0,</p>
<pre><code>data:{}||[],

msg:’’
</code></pre><p>  }</p>
<p>status: 接口的执行的状态<br>=0表示成功</p>
<p>&lt;0 表示有异常=””<br>Data 接口的主数据<br>可以根据实际返回数组或JSON对象<br>Msg 信息<br>当status!=0 都应该有错误信息</p>
<h1 id="9-非Restful-Api的需求"><a href="#9-非Restful-Api的需求" class="headerlink" title="9. 非Restful Api的需求"></a>9. 非Restful Api的需求</h1><p>由于实际业务开展过程中，可能会出现各种的api不是简单的restful 规范能实现的，因此，需要有一些api突破restful规范原则。特别是移动互联网的api设计，更需要有一些特定的api来优化数据请求的交互。</p>
<h2 id="9-1-页面级的api"><a href="#9-1-页面级的api" class="headerlink" title="9.1 页面级的api"></a>9.1 页面级的api</h2><p>把当前页面中需要用到的所有数据通过一个接口一次性返回全部数据<br>举例<br>api/v1/get-home-data 返回首页用到的所有数据<br>这类API有一个非常不好的地址，只要业务需求变动，这个api就需要跟着变更。</p>
<h2 id="9-2-自定义组合api"><a href="#9-2-自定义组合api" class="headerlink" title="9.2 自定义组合api"></a>9.2 自定义组合api</h2><p>把当前用户需要在第一时间内容加载的多个接口合并成一个请求发送到服务端，服务端根据请求内容，一次性把所有数据合并返回,相比于页面级api，具备更高的灵活性，同时又能很容易的实现页面级的api功能。<br>规范<br>地址：api/v1/batApi<br>传入参数：</p>
<p>  data:[<br>      {url:’api1’,type:’get’,data:{…}},</p>
<pre><code>{url:&apos;api2&apos;,type:&apos;get&apos;,data:{...}},

{url:&apos;api3&apos;,type:&apos;get&apos;,data:{...}},

{url:&apos;api4&apos;,type:&apos;get&apos;,data:{...}}
</code></pre><p>  ]</p>
<p>返回数据</p>
<p>  {<br>      status:0,<br>      msg:’’,<br>      data:[<br>          {status:0,msg:’’,data:[]},</p>
<pre><code>    {status:-1,msg:&apos;&apos;,data:{}},

    {status:1,msg:&apos;&apos;,data:{}},

    {status:0,msg:&apos;&apos;,data:[]},
]
</code></pre><p>  }</p>
<h1 id="10-Api共建平台"><a href="#10-Api共建平台" class="headerlink" title="10. Api共建平台"></a>10. Api共建平台</h1><p>RAP是一个GUI的WEB接口管理工具。在RAP中，您可定义接口的URL、请求&amp;响应细节格式等等。通过分析这些数据，RAP提供MOCK服务、测试服务等自动化工具。RAP同时提供大量企业级功能，帮助企业和团队高效的工作。</p>
<h2 id="10-1-什么是RAP"><a href="#10-1-什么是RAP" class="headerlink" title="10.1 什么是RAP?"></a>10.1 什么是RAP?</h2><p>在前后端分离的开发模式下，我们通常需要定义一份接口文档来规范接口的具体信息。如一个请求的地址、有几个参数、参数名称及类型含义等等。RAP 首先方便团队录入、查看和管理这些接口文档，并通过分析结构化的文档数据，重复利用并生成自测数据、提供自测控制台等等… 大幅度提升开发效率。</p>
<h2 id="10-2-RAP的特色"><a href="#10-2-RAP的特色" class="headerlink" title="10.2 RAP的特色"></a>10.2 RAP的特色</h2><p>强大的GUI工具 给力的用户体验，你将会爱上使用RAP来管理您的API文档。<br>完善的MOCK服务 文档定义好的瞬间，所有接口已经准备就绪。有了MockJS，无论您的业务模型有多复杂，它都能很好的满足。<br>庞大的用户群 RAP在阿里巴巴有200多个大型项目在使用，也有许多著名的公司、开源人士在使用。RAP跟随这些业务的成行而成长，专注细节，把握质量，经得住考验。</p>

      
    </div>
    <footer class="article-footer">
      <a data-url="http://ikohoo.com/blog/2017/09/07/api-specification/" data-id="cja3l1mrh00184stkmquxh2ng" class="article-share-link">Partager</a>
      
      
  <ul class="article-tag-list"><li class="article-tag-list-item"><a class="article-tag-list-link" href="/blog/tags/RESTful/">RESTful</a></li></ul>

    </footer>
  </div>
  
    
<nav id="article-nav">
  
    <a href="/blog/2017/09/07/restful-api-practice/" id="article-nav-newer" class="article-nav-link-wrap">
      <strong class="article-nav-caption">Récent</strong>
      <div class="article-nav-title">
        
          RESTful API 设计最佳实践
        
      </div>
    </a>
  
  
    <a href="/blog/2017/07/19/machine-learn-route/" id="article-nav-older" class="article-nav-link-wrap">
      <strong class="article-nav-caption">Ancien</strong>
      <div class="article-nav-title">机器学习路线图(附资料)</div>
    </a>
  
</nav>

  
</article>

</section>
        
          <aside id="sidebar">
  
    
  <div class="widget-wrap">
    <h3 class="widget-title">Catégories</h3>
    <div class="widget">
      <ul class="category-list"><li class="category-list-item"><a class="category-list-link" href="/blog/categories/AI/">AI</a></li><li class="category-list-item"><a class="category-list-link" href="/blog/categories/Big-Data/">Big Data</a></li><li class="category-list-item"><a class="category-list-link" href="/blog/categories/CloudCompute/">CloudCompute</a></li><li class="category-list-item"><a class="category-list-link" href="/blog/categories/Efficiency/">Efficiency</a></li><li class="category-list-item"><a class="category-list-link" href="/blog/categories/RESTful-API/">RESTful API</a></li><li class="category-list-item"><a class="category-list-link" href="/blog/categories/skills/">skills</a></li><li class="category-list-item"><a class="category-list-link" href="/blog/categories/数据仓库/">数据仓库</a></li></ul>
    </div>
  </div>


  
    
  <div class="widget-wrap">
    <h3 class="widget-title">Mot-clés</h3>
    <div class="widget">
      <ul class="tag-list"><li class="tag-list-item"><a class="tag-list-link" href="/blog/tags/AI/">AI</a></li><li class="tag-list-item"><a class="tag-list-link" href="/blog/tags/Big-Data/">Big Data</a></li><li class="tag-list-item"><a class="tag-list-link" href="/blog/tags/CloudCompute/">CloudCompute</a></li><li class="tag-list-item"><a class="tag-list-link" href="/blog/tags/CloudStack/">CloudStack</a></li><li class="tag-list-item"><a class="tag-list-link" href="/blog/tags/Docker/">Docker</a></li><li class="tag-list-item"><a class="tag-list-link" href="/blog/tags/Efficiency/">Efficiency</a></li><li class="tag-list-item"><a class="tag-list-link" href="/blog/tags/Eucalyptus/">Eucalyptus</a></li><li class="tag-list-item"><a class="tag-list-link" href="/blog/tags/FusionCloud/">FusionCloud</a></li><li class="tag-list-item"><a class="tag-list-link" href="/blog/tags/HBase/">HBase</a></li><li class="tag-list-item"><a class="tag-list-link" href="/blog/tags/Hadoop/">Hadoop</a></li><li class="tag-list-item"><a class="tag-list-link" href="/blog/tags/Hive/">Hive</a></li><li class="tag-list-item"><a class="tag-list-link" href="/blog/tags/Openstack/">Openstack</a></li><li class="tag-list-item"><a class="tag-list-link" href="/blog/tags/RESTful/">RESTful</a></li><li class="tag-list-item"><a class="tag-list-link" href="/blog/tags/Resource/">Resource</a></li><li class="tag-list-item"><a class="tag-list-link" href="/blog/tags/Slack/">Slack</a></li><li class="tag-list-item"><a class="tag-list-link" href="/blog/tags/Spark/">Spark</a></li><li class="tag-list-item"><a class="tag-list-link" href="/blog/tags/Team-Management/">Team Management</a></li><li class="tag-list-item"><a class="tag-list-link" href="/blog/tags/Wiki/">Wiki</a></li><li class="tag-list-item"><a class="tag-list-link" href="/blog/tags/cloudcompute/">cloudcompute</a></li><li class="tag-list-item"><a class="tag-list-link" href="/blog/tags/lucene/">lucene</a></li><li class="tag-list-item"><a class="tag-list-link" href="/blog/tags/markdown/">markdown</a></li><li class="tag-list-item"><a class="tag-list-link" href="/blog/tags/solr/">solr</a></li><li class="tag-list-item"><a class="tag-list-link" href="/blog/tags/startup/">startup</a></li><li class="tag-list-item"><a class="tag-list-link" href="/blog/tags/数据仓库/">数据仓库</a></li></ul>
    </div>
  </div>


  
    
  <div class="widget-wrap">
    <h3 class="widget-title">Nuage de mot-clés</h3>
    <div class="widget tagcloud">
      <a href="/blog/tags/AI/" style="font-size: 10px;">AI</a> <a href="/blog/tags/Big-Data/" style="font-size: 18px;">Big Data</a> <a href="/blog/tags/CloudCompute/" style="font-size: 16px;">CloudCompute</a> <a href="/blog/tags/CloudStack/" style="font-size: 10px;">CloudStack</a> <a href="/blog/tags/Docker/" style="font-size: 10px;">Docker</a> <a href="/blog/tags/Efficiency/" style="font-size: 14px;">Efficiency</a> <a href="/blog/tags/Eucalyptus/" style="font-size: 10px;">Eucalyptus</a> <a href="/blog/tags/FusionCloud/" style="font-size: 10px;">FusionCloud</a> <a href="/blog/tags/HBase/" style="font-size: 10px;">HBase</a> <a href="/blog/tags/Hadoop/" style="font-size: 10px;">Hadoop</a> <a href="/blog/tags/Hive/" style="font-size: 10px;">Hive</a> <a href="/blog/tags/Openstack/" style="font-size: 10px;">Openstack</a> <a href="/blog/tags/RESTful/" style="font-size: 12px;">RESTful</a> <a href="/blog/tags/Resource/" style="font-size: 10px;">Resource</a> <a href="/blog/tags/Slack/" style="font-size: 12px;">Slack</a> <a href="/blog/tags/Spark/" style="font-size: 10px;">Spark</a> <a href="/blog/tags/Team-Management/" style="font-size: 14px;">Team Management</a> <a href="/blog/tags/Wiki/" style="font-size: 20px;">Wiki</a> <a href="/blog/tags/cloudcompute/" style="font-size: 10px;">cloudcompute</a> <a href="/blog/tags/lucene/" style="font-size: 10px;">lucene</a> <a href="/blog/tags/markdown/" style="font-size: 10px;">markdown</a> <a href="/blog/tags/solr/" style="font-size: 10px;">solr</a> <a href="/blog/tags/startup/" style="font-size: 14px;">startup</a> <a href="/blog/tags/数据仓库/" style="font-size: 10px;">数据仓库</a>
    </div>
  </div>

  
    
  <div class="widget-wrap">
    <h3 class="widget-title">Archives</h3>
    <div class="widget">
      <ul class="archive-list"><li class="archive-list-item"><a class="archive-list-link" href="/blog/archives/2017/11/">十一月 2017</a></li><li class="archive-list-item"><a class="archive-list-link" href="/blog/archives/2017/09/">九月 2017</a></li><li class="archive-list-item"><a class="archive-list-link" href="/blog/archives/2017/07/">七月 2017</a></li><li class="archive-list-item"><a class="archive-list-link" href="/blog/archives/2017/06/">六月 2017</a></li><li class="archive-list-item"><a class="archive-list-link" href="/blog/archives/2017/05/">五月 2017</a></li><li class="archive-list-item"><a class="archive-list-link" href="/blog/archives/2017/02/">二月 2017</a></li><li class="archive-list-item"><a class="archive-list-link" href="/blog/archives/2016/06/">六月 2016</a></li><li class="archive-list-item"><a class="archive-list-link" href="/blog/archives/2016/05/">五月 2016</a></li><li class="archive-list-item"><a class="archive-list-link" href="/blog/archives/2016/03/">三月 2016</a></li><li class="archive-list-item"><a class="archive-list-link" href="/blog/archives/2016/02/">二月 2016</a></li><li class="archive-list-item"><a class="archive-list-link" href="/blog/archives/2015/12/">十二月 2015</a></li><li class="archive-list-item"><a class="archive-list-link" href="/blog/archives/2015/11/">十一月 2015</a></li><li class="archive-list-item"><a class="archive-list-link" href="/blog/archives/2015/10/">十月 2015</a></li><li class="archive-list-item"><a class="archive-list-link" href="/blog/archives/2015/09/">九月 2015</a></li><li class="archive-list-item"><a class="archive-list-link" href="/blog/archives/2015/08/">八月 2015</a></li><li class="archive-list-item"><a class="archive-list-link" href="/blog/archives/2015/06/">六月 2015</a></li></ul>
    </div>
  </div>


  
    
  <div class="widget-wrap">
    <h3 class="widget-title">Articles récents</h3>
    <div class="widget">
      <ul>
        
          <li>
            <a href="/blog/2017/11/17/build-warehouse/">搭建数据仓库的流程简介</a>
          </li>
        
          <li>
            <a href="/blog/2017/09/19/centos-lamp/">CentOS下yum安装LAMP</a>
          </li>
        
          <li>
            <a href="/blog/2017/09/19/mysql-user/">Mysql用户和权限管理</a>
          </li>
        
          <li>
            <a href="/blog/2017/09/18/unicode/">Unicode(UTF-8, UTF-16)令人混淆的概念</a>
          </li>
        
          <li>
            <a href="/blog/2017/09/07/restful-api-practice/">RESTful API 设计最佳实践</a>
          </li>
        
      </ul>
    </div>
  </div>

  
</aside>
        
      </div>
      <footer id="footer">
  
  <div class="outer">
    <div id="footer-info" class="inner">
      &copy; 2017 Leo.Liu<br>
      Propulsé by <a href="http://hexo.io/" target="_blank">Hexo</a>
    </div>
  </div>
</footer>
    </div>
    <nav id="mobile-nav">
  
    <a href="/blog/" class="mobile-nav-link">Home</a>
  
    <a href="/blog/archives" class="mobile-nav-link">Archives</a>
  
</nav>
    

<script src="//ajax.googleapis.com/ajax/libs/jquery/2.0.3/jquery.min.js"></script>


  <link rel="stylesheet" href="/blog/fancybox/jquery.fancybox.css">
  <script src="/blog/fancybox/jquery.fancybox.pack.js"></script>


<script src="/blog/js/script.js"></script>

  </div>
</body>
</html>